This document describes the ZoneRanger application, and is divided into the following sections:
Background Information
About ZoneRanger
Overview Window
Zone Window
Apple Menu
File Menu
Edit Menu
Configure Menu
Special Menu
Help Menu
Overview Window Popup Menu : Name Column
Overview Window Popup Menu : Summary Columns
Zone Window Popup Menu
Find Dialog
Shortcuts
Customizing ZoneRanger
System Requirements
Known Limitations
Copyright Notice
Special Thanks
Comments and Suggestions
The reader is encouraged to read the entire document; if, however, one wants to get off to a quick start, one should read from the "System Requirements" section to the end of the document.
B A C K G R O U N D I N F O R M A T I O N
Each process on the Macintosh is associated with a heap zone, out of which the Memory Manager allocates memory blocks on behalf of the process. A heap zone contains a zone header followed by a series of memory blocks, each of which contains a block header followed by the contents of the block. A block header contains the size, type, and attributes of the block.
A block type is either relocatable, non-relocatable, or free. A relocatable block is one that the Memory Manager can move around the heap zone as needed, and contains the data that is referenced by a handle. A non-relocatable block is one that cannot move around the heap zone, and contains the data that is referenced by a pointer. A free block is unallocated, and the contents of the block are undefined. For the sake of simplicity, we shall refer to relocatable blocks as handles and non-relocatable blocks as pointers.
There are three block attributes, and they apply only to relocatable blocks: locked, purgeable, and resource. If a relocatable block has the locked attribute set, then it cannot be moved around the heap zone. If a relocatable block has the purgeable attribute set, then it can be converted to a free block if necessary. If a relocatable block has the resource attribute set, then it contains the data from a resource. For the sake of simplicity, we shall refer to these types of blocks as locked handles, purgeable handles, and resource handles, respectively.
The reader is referred to the "Memory" volume of "Inside Macintosh" for more detailed information about the structure of heap zones and memory blocks.
A B O U T Z O N E R A N G E R
ZoneRanger provides detailed information about each heap zone that is currently active on the Macintosh. This information includes both the counts and total sizes of the free blocks, pointers, handles, locked handles, purgeable handles, and resource handles in each heap zone.
ZoneRanger also provides windows in which a heap zone can be displayed graphically, with the size, type, and attributes of each block clearly defined. The user can control the resolution and zoom factor of this display, as well as click on any individual block to view its contents.
ZoneRanger can save to a TEXT file the detailed information about all blocks in a given heap zone, or summary information about all active heap zones. The graphical display of any heap zone can also be saved to a PICT file.
O V E R V I E W W I N D O W
There are two types of windows in ZoneRanger, a single Overview window and a set of Zone windows. Balloon help is available for all windows.
The Overview window is divided into seven columns, and has one row for each currently active heap zone. The first column is titled "Name" and contains the name of the process associated with the heap zone. The next three columns are titled "Free Blocks", "Pointers", and "Handles…", and contain the numbers of free blocks, pointers, and handles in the heap zone. The final three columns are titled with icons representing locked, purgeable, and resource handles, and contain the numbers of locked, purgeable, and resource handles, respectively.
Although the Overview window defaults to displaying the numbers of the different types of blocks, the user can configure whether the Overview window displays the numbers, total sizes, or percentage of these different block types in the heap zone. The user can also configure whether these figures are displayed in decimal or hexadecimal notation.
The user can click on the "Name" column of any heap zone in the Overview window in order to pop up a list of operations that can be performed on that heap zone. In addition, the user can click on any other column in the window in order to pop up a list of blocks that are summarized in that column. For example, if the user clicks on the "Free Blocks" column of the System heap zone, a list of all the free blocks in the System heap will be popped up. These lists can be either copied to the clipboard or saved to a TEXT file.
If Balloon Help is enabled when the user clicks on any column, then help balloons will appear which explain the contents of the popup menu in more detail. One should read the "Overview Window Popup Menus" section for a complete description of these menus.
Lastly, the contents of the Overview window can be saved to a TEXT file.
Z O N E W I N D O W
The user can open one Zone window for each heap zone that is listed in the Overview window. The zone window displays a graphic representation of the heap zone in two dimensions. Each type of block in distinguished by the colored pattern in which it is drawn.
On a color monitor, free blocks are drawn in green, handles are drawn in yellow, and pointers are drawn in red. On a monochrome monitor, free blocks are drawn in white, handles are drawn in gray, and pointers are drawn in black. For information on how to customize the colors and patterns that are used, one should read the "Customizing ZoneRanger" section.
Although memory is inherently one-dimensional, the second dimension of the graphical display is achieved by wrapping the display to the width of the window. Specifically, the zone window is a two-dimensional grid in which each square represents a fixed number of bytes in the heap zone. This number of bytes is referred to as the "resolution" of the zone window, and can be configured by the user. If a given block is larger than the current resolution, then it will appear in the display as spanning the appropriate number of grid squares. If the given block is smaller than the current resolution, then it would occupy less than a single grid square, and may not appear in the display at all. Since even the smallest block must contain the block header which is either 8 or 12 bytes, one should set the resolution to 8 bytes in order to ensure that all blocks are displayed. The default resolution for a zone window is 32 bytes.
In addition, the user can configure the pixel size of each grid square, which is referred to as the "zoom factor" of the zone window. The allowable zoom factors are 1x1, 4x4, and 8x8 pixel squares. The default zoom factor for a zone window is 4x4.
The user can also configure whether the boundaries of each individual block are shown. In "Block View", all of the grid squares that comprise a given block are displayed as a contiguous set, and the boundaries of the block are clearly marked. In "Grid View", each grid square is drawn using the pattern representing the type of block in which it is contained, but there is no indication of where one block ends and the next one begins. The grid view of a heap zone presents less information than the block view, but can be drawn faster because it does not have to calculate and draw the block boundaries.
In addition, the user can click on any block in the heap zone to pop up information about the block and a display of its contents, both of which can be either copied to the clipboard or saved to a TEXT file. If Balloon Help is enabled when the user clicks on the block, then help balloons will appear which explain information about the contents of the block in more detail. One should read the "Zone Window Popup Menu" section for a complete description of this functionality.
Finally, the contents of a Zone window can be saved to either a TEXT file or a PICT file.
A P P L E M E N U
ZoneRanger contains four menus: "File", "Edit", "Configure", and "Special". It also adds menu items to the standard Apple and Help menus. Balloon help is available for all menus.
The Apple menu contains two menu items belonging to ZoneRanger, "About ZoneRanger…" and "Legend…".
The "About ZoneRanger…" menu item opens the about box for ZoneRanger.
The "Legend…" menu item opens a dialog which contains a description of which colored patterns are used to display each of the different block types in a Zone window. This menu item is active when a Zone window is frontmost. For information on how to customize the colors and patterns that are used in a Zone window, one should read the "Customizing ZoneRanger" section.
F I L E M E N U
The File menu contains five menu items: "Open", "Close", "Save As Text", "Save As Picture", and "Quit".
The "Open" menu item is used to open the Overview window or a Zone window. This menu item presents a submenu that contains the "Overview" menu item, and one menu item for each of the heap zones that is listed in the Overview window. The "Overview" menu item will open the Overview window, or bring the window to the front if it is already open. The remaining menu items will each open a Zone window displaying the heap zone for the process for which the menu item is named, or bring the window to the front if it is already open.
The "Close" menu item closes the frontmost window. This menu item is active when there is a window open.
The "Save As Text" menu item will save the contents of the frontmost window to a TEXT file. If the Overview window is frontmost, it will save the displayed summary information. If a Zone window is frontmost, it will save the detailed information about each block in the heap zone to a TEXT file. This information includes the block's type, address, size, attributes, and first 32 bytes of the block's contents in both hexadecimal and ASCII format. In addition, if the block is a resource handle, the information will include the type, id, and name of the resource, as well as the name of the resource file containing the resource. This menu item is active when there is a window open.
The "Save As Picture" menu item will save the graphical display of the heap zone to a PICT file. This display will include the entire contents of the heap zone, not just the currently visible portion. This menu item is active when a Zone window is frontmost.
The "Quit" menu item quits the ZoneRanger application.
E D I T M E N U
The Edit menu contains the menu items for performing the required editing operations, "Undo", "Cut", "Copy", "Paste", and "Clear". None of these menu items is used by ZoneRanger.
The Edit menu contains two additional menu items, "Find…" and "Cancel Find".
The "Find…" menu item opens the Find Dialog, which is used to find blocks that are of a certain type, certain size, or contain a certain pattern. One should read the "Find Dialog" section for a complete description of this dialog. This menu item is active when a Zone window is frontmost.
The "Cancel Find" menu item cancels the current find operation. This menu item is active when a Zone window is frontmost, and a find operation has been performed.
C O N F I G U R E M E N U
The Configure menu contains menu items that the user can use to configure the display of the frontmost window.
The "Display Block Sizes" menu item sets the Overview window to display the total sizes of the various types of blocks in each heap zone. Selecting this menu item will place a checkmark next to the item, and will deselect "Display Block Counts" and "Display Block Usage". This menu item is active when the Overview window is frontmost.
The "Display Block Counts" menu item sets the Overview window to display the total counts of the various types of blocks in each heap zone. Selecting this menu item will place a checkmark next to the item, and will deselect "Display Block Sizes" and "Display Block Usage". This menu item is active when the Overview window is frontmost.
The "Display Block Usage" menu item sets the Overview window to display the usage thermometer of the various types of blocks in each heap zone. A usage thermometer shows the percentage of the entire heap zone occupied by blocks of the given type. Selecting this menu item will place a checkmark next to the item, and will deselect "Display Block Sizes" and "Display Block Counts". This menu item is active when the Overview window is frontmost.
The "Display Decimal" menu item sets the frontmost window to display all numbers in decimal notation. Selecting this menu item will place a checkmark next to the item, and will deselect "Display Hexadecimal". This menu item is active when a window is open.
The "Display Hexadecimal" menu item sets the frontmost window to display all numbers in hexadecimal notation. Selecting this menu item will place a checkmark next to the item, and will deselect "Display Decimal". This menu item is active when a window is open.
The "Block View" menu item sets the Zone window to display the boundaries of each block in the zone. Selecting this menu item will place a checkmark next to the item, and will deselect "Grid View". This menu item is active when a Zone window is frontmost.
The "Grid View" menu item sets the Zone window to suppress the display of the boundaries of each block in the zone. Selecting this menu item will place a checkmark next to the item, and will deselect "Block View". This menu item is active when a Zone window is frontmost.
The "Show Locked Handles" menu item will display all locked handles in a 50% red color on a color monitor, or in a dark gray pattern on a monochrome monitor. Selecting this menu item will place a checkmark next to the item, and will deselect "Show Purgeable Handles" and "Show Resource Handles". This menu item is active when a Zone window is frontmost.
The "Show Purgeable Handles" menu item will display all purgeable handles in a 50% green color on a color monitor, or in a light gray pattern on a monochrome monitor. Selecting this menu item will place a checkmark next to the item, and will deselect "Show Locked Handles" and "Show Resource Handles". This menu item is active when a Zone window is frontmost.
The "Show Resource Handles" menu item will display all resource handles in a magenta color on a color monitor, or in a diamond pattern on a monochrome monitor. Selecting this menu item will place a checkmark next to the item, and will deselect "Show Locked Handles" and "Show Purgeable Handles". This menu item is active when a Zone window is frontmost.
For information on how to customize the colors and patterns that are used in a Zone window, one should read the "Customizing ZoneRanger" section.
The "Increase Resolution" menu item increases the resolution of the display by a factor of two. It accomplishes this by halving the number of bytes represented by each grid square. The maximum allowable resolution is 8 bytes per grid square. This menu item is active when a Zone window is frontmost, and the resolution is not already at the maximum.
The "Decrease Resolution" menu item decreases the resolution of the display by a factor of two. It accomplishes this by doubling the number of bytes represented by each grid square. The minimum allowable resolution is 1,048,576 bytes (one megabyte) per grid square. This menu item is active when a Zone window is frontmost, and the resolution is not already at the minimum.
The "Zoom In" menu item increases the size of each grid square in the display. The allowable zoom factors are 1x1, 4x4, and 8x8 pixel grid squares. Furthermore, the 1x1 pixel zoom factor is not available when the display is in "Block View", since a one pixel square is not sufficiently large to draw the outline of the block. This menu item is active when a Zone window is frontmost, and the zoom factor is not already at the maximum.
The "Zoom Out" menu item decreases the size of each grid square in the display. The allowable zoom factors are 1x1, 4x4, and 8x8 pixel grid squares. Furthermore, the 1x1 pixel zoom factor is not available when the display is in "Block View", since a one pixel square is not sufficiently large to draw the outline of the block. This menu item is active when a Zone window is frontmost, and the zoom factor is not already at the minimum.
The "Refresh Foreground" menu item presents a "slider" submenu from which the user can specify how often the application will refresh the windows when the application is in the foreground. The user can choose a value in the range from 1 to 5 seconds, as well as "always" or "never".
The "Refresh Background" menu item presents a "slider" submenu from which the user can specify how often the application will refresh the windows when the application is in the background. The user can choose a value in the range from 1 to 5 seconds, as well as "always" or "never".
S P E C I A L M E N U
The Special menu contains menu items that perform a variety of specialized operations.
The "Debugger…" menu item drops the user down into the installed debugger. To return to ZoneRanger from the debugger, the user should issue the appropriate "go" command for the debugger. From MacsBug, the user should type "g" followed by a carriage return. From The Debugger from Jasik Designs, the user should select "Exit To Program" from the "Go" menu. This menu item is active when a debugger is installed, and has been tested with MacsBug and The Debugger. It should also be active when TMON is installed.
The "Compact" menu item compacts the heap zone. The compaction process involves moving unlocked handles toward the bottom of the heap, and merging together free blocks. This menu item is active when a Zone window is frontmost.
The "Purge" menu item purges the heap zone. The purging process involves changing unlocked, purgeable handles to free blocks. This menu item is active when a Zone window is frontmost.
The "Compact and Purge" menu item compacts and purges the heap zone. The purging process involves changing unlocked, purgeable handles to free blocks; the compaction process involves moving unlocked handles toward the bottom of the heap, and merging together free blocks. This menu item is active when a Zone window is frontmost.
The "Bring To Front" menu item bring the process associated with the heap zone to the front; that is, makes it the current application. This menu item is active when a Zone window is frontmost, the process for the heap zone is not background-only, and the process is not already frontmost.
H E L P M E N U
The Help menu contains standard menu items that are used for Balloon Help, and is available on Macintoshes that are running System 7 or later.
The "About Balloon Help…" menu item opens a dialog which contains information about Balloon Help.
The "Show Balloons" menu item turns on Balloon Help. When Balloon Help is on, ZoneRanger provides help balloons for all menus, popup menus, and windows. When the menu item is selected, its name changes to "Hide Balloons". Selecting the menu item again will turn off Balloon Help.
O V E R V I E W W I N D O W P O P U P M E N U : N A M E C O L U M N
The popup menu for the "Name" column in the Overview window contains menu items that perform operations on the heap zone that is currently selected in the window.
The "Open Zone…" menu item opens a Zone window for the selected heap zone. This is equivalent to choosing the menu item for the appropriate heap zone from the "Open" menu item on the File menu.
The "Compact", "Purge", "Compact and Purge", and "Bring To Front" menu items perform the same operations on the selected heap zone as the same menu items on the Special menu perform on the frontmost Zone window. One should read the "Special Menu" section for a complete description of these items.
O V E R V I E W W I N D O W P O P U P M E N U : S U M M A R Y C O L U M N S
The popup menu for all columns in the Overview window other than the "Name" column contains a list of those blocks that are summarized in that column. For example, if the user clicks on the "Free Blocks" column of the System heap zone, a list of all the free blocks in the System heap will be popped up.
This popup menu will contain the number and total physical size of all of the blocks summarized in that column, as well as the type, size, and attributes of each individual block. For those individual blocks that are resources, the type, id, and name of the resource will also be displayed. One should read the help balloons for this popup menu for a more complete description of this information.
The "Options…" menu item at the bottom of the popup menu presents a submenu that contains the "Copy To Clipboard" and "Save To File…" menu items.
The "Copy To Clipboard" menu item will copy the contents of the popup menu, i.e. the information about the blocks summarized in that column, to the Clipboard.
The "Save To File…" menu item will allow the user to save the contents of the popup menu, i.e. the information about the blocks summarized in that column, to a TEXT file.
Z O N E W I N D O W P O P U P M E N U
The popup menu for the Zone window contains information about and the contents of the block that is currently selected in the window.
The information about the block includes its type, size, address, and attributes. If the block is a resource handle, then the information also includes the type, id, and name of the resource. One should read the help balloons for this popup menu for a more complete description of this information.
The contents of the block are displayed in 8 byte increments, with a hexadecimal display of the bytes on the left and an ASCII display on the right. If the size of the block is greater than 256 bytes, then only the first 256 bytes of the contents will be displayed.
The "Options…" menu item at the bottom of the popup menu presents a submenu that contains the "Copy To Clipboard" and "Save To File…" menu items.
The "Copy To Clipboard" menu item will copy the contents of the popup menu, i.e. the information about and the contents of the selected block, to the Clipboard.
The "Save To File…" menu item will allow the user to save the contents of the popup menu, i.e. the information about and the contents of the selected block, to a TEXT file.
F I N D D I A L O G
The Find dialog allows the user to find those blocks in a Zone window that are of a certain type, certain size, or contain a certain pattern. Once the user has specified one or more of these criteria, then any blocks that qualify (satisfy all of the specified criteria) will be hilited.
On a color monitor, the found blocks will be hilited in blue; on a monochrome monitor, they will be hilited in a diagonal pattern. For information on how to customize the colors and patterns that are used in a Zone window, one should read the "Customizing ZoneRanger" section.
The Find dialog is divided into three sections, one for each of the criteria: "Block Type", "Block Size", and "Block Contents".
The "Block Type" section allows the user to specify the type of block. The section contains three radio buttons and three checkboxes.
The "All" radio button specifies that all blocks qualify.
The "Pointer" radio button specifies that only pointers qualify.
The "Handle" radio button specifies that only handles qualify.
The "Locked" checkbox specifies the locked status that a handle must have to qualify: checked -> locked, unchecked -> unlocked.
The "Purgeable" checkbox specifies the purgeable status that a handle must have to qualify: checked -> purgeable, unchecked -> non-purgeable.
The "Resource" checkbox specifies the resource status that a handle must have to qualify: checked -> resource, unchecked -> non-resource.
The "Block Size" section allows the user to specify the size of the block. The section contains two entry boxes.
The first entry box specifies the minimum size that a block must have to qualify.
The second box specifies the maximum size that a block must have to qualify.
If both boxes are empty, then all block sizes qualify.
The "Block Contents" section allows the user to specify a pattern that the block must contain. The section contains one entry box, two radio buttons, and one checkbox.
The entry box specifies the pattern that a block must contain to qualify.
The "ASCII" radio button specifies that the pattern is an ASCII string, and must contain an arbitrary number of ASCII characters.
The "Hexadecimal" radio button specifies that the pattern is a hexadecimal string, and must contain an even number of the characters 0-9, A-F.
The "Case Sensitive" checkbox specifies whether the search for an ASCII string should be sensitive to the case of the string.
Command-key equivalents are available for all dialog items; hold down the option key when the dialog is open to display these equivalents. One should read the help balloons for this dialog for a more complete description of its dialog items.
S H O R T C U T S
There are a handful of shortcuts that are available for ZoneRanger.
If Balloon Help is available, then holding down the option key when clicking the mouse in a menu will turn on the help balloons until the mouse button is released. Similarly, holding down the option key when opening a popup menu will turn on the help balloons until the mouse button is released. This is a useful way to quickly receive help for a menu item or items without explicitly turning Balloon Help on and off manually.
Holding down the command key will turn on the "Display Block Sizes" menu item as long as the key remains depressed. This shortcut works whether ZoneRanger is in the foreground or the background. This is a useful way to toggle between display modes temporarily, without having to bring ZoneRanger to the foreground or go to the Configure menu.
Holding down the option key will turn on the "Display Block Counts" menu item as long as the key remains depressed. This shortcut works whether ZoneRanger is in the foreground or the background. This is a useful way to toggle between display modes temporarily, without having to bring ZoneRanger to the foreground or go to the Configure menu.
Holding down the control key will turn on the "Display Block Usage" menu item as long as the key remains depressed. This shortcut works whether ZoneRanger is in the foreground or the background. This is a useful way to toggle between display modes temporarily, without having to bring ZoneRanger to the foreground or go to the Configure menu.
When the Find Dialog is open, holding down the option key will display the command key equivalents for all of the dialog items, as long as the key remains depressed. If Balloon Help is available, then the help balloons will be turned on while the option key is pressed.
When a Zone window is frontmost, the scroll bar can be controlled entirely from the keyboard. The "Up Arrow" and "Down Arrow" keys will scroll the window up and down one line at a time, the "Page Up" and "Page Down" keys will scroll the window up and down one page at a time, and the "Home" and "End" keys will scroll to the top or bottom of the window.
C U S T O M I Z I N G Z O N E R A N G E R
ZoneRanger distinguishes the different types of blocks in a Zone window by the colored pattern in which each is drawn. On a color monitor, the following colored patterns are used:
Free Blocks - Green
Purgeable Handles - 50% Green
Handles - Yellow
Locked Handles - 50% Red
Pointers - Red
Resource Handles - Magenta
Found Blocks - Blue
On a monochrome monitor, the following patterns are used:
Free Blocks - White
Purgeable Handles - Light Gray
Handles - Gray
Locked Handles - Dark Gray
Pointers - Black
Resource Handles - Diamond
Found Blocks - Diagonal
The patterns that are used are stored in 'PAT#' resources in the resource fork of the ZoneRanger application. Each resource has been given a name that indicates the type of block it is used for, and contains three patterns that are used for the three zoom factors: 1x1 pixel squares, 4x4 pixel squares, and 8x8 pixel squares.
The colors that are used are stored in 'STR ' resources in the resource fork of the ZoneRanger application. Each resource has been given a name that indicates the type of block it is used for, and contains the case-sensitive name of a classic QuickDraw color:
blackColor
whiteColor
redColor
greenColor
blueColor
cyanColor
magentaColor
yellowColor
To customize the patterns and colors that are used by ZoneRanger, one should copy the appropriate resources from the ZoneRanger application, paste them into the "ZoneRanger Preferences" file located in the Preferences folder inside the System folder, and then modify the resources appropriately. Although it is possible to modify the resources in the ZoneRanger application itself, this is not recommended.
For example, to change the colored pattern used for purgeable blocks in block view from 50% green to 100% cyan, one should copy the following resources from the ZoneRanger application to the "ZoneRanger Preferences" file:
'PAT#', "Color : Block View : Purgeable Blocks"
'STR ', "Color : Purgeable Blocks"
Then, change the 'PAT#' resource to contain a black pattern instead of 50% gray pattern, and the 'STR ' resource to contain the string "cyanColor" instead of "greenColor".
S Y S T E M R E Q U I R E M E N T S
ZoneRanger requires System 7 or later.
K N O W N L I M I T A T I O N S
ZoneRanger makes every attempt to operate smoothly under low-memory conditions; the Macintosh Toolbox, however, does not. As such, if the application runs out of memory during a toolbox call, ZoneRanger will return to the Finder without any warning to the user. Since the application is already out of memory, the trick is to determine how to inform the user of what has happened without allocating any memory.
ZoneRanger is free; it may be freely copied and distributed, provided that this copyright notice is preserved on all copies. The software may not, however, be sold or distributed for profit, or included with other software which is sold or distributed for profit, without the permission of Metrowerks.
S P E C I A L T H A N K S
The string search algorithm used by the Find dialog was implemented by Mike Engber; all of the remaining source code for ZoneRanger was written by the author. One must also thank, however, Eric Hanig and Mike Engber for the numerous suggestions they have made regarding the feature set and user interface.
C O M M E N T S A N D S U G G E S T I O N S
If you find any bugs with the program, or have any comments or suggestions you would like to make, please contact:
